home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / xdsn217.zip / DOC / h2d.inf (.txt) < prev    next >
OS/2 Help File  |  1996-07-09  |  53KB  |  1,756 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Disclaimer ΓòÉΓòÉΓòÉ
  3.  
  4. This on-line document was generated automatically from its printed version 
  5. LaTeX source. Some places in the document (especially tables) may look ugly due 
  6. to the conversion program limits. These problems are being worked on and are 
  7. supposed to be solved in the final release. 
  8.  
  9.  
  10. ΓòÉΓòÉΓòÉ 2. Title Page ΓòÉΓòÉΓòÉ
  11.  
  12.  xTech Development System 
  13.  
  14.  H2D User's Guide 
  15.  
  16.  xTech Ltd, 1996 
  17.  
  18. XDS software and documentation copyright (c) 1991-1996 xTech Ltd. (xTech). 
  19.  
  20. Information in this document is subject to change without notice and does not 
  21. represent a commitment on the part of xTech. 
  22.  
  23. All rights reserved. You may use the enclosed software on a single computer; 
  24. transfer the software from one computer to another, provided that the software 
  25. is used on only one computer at a time and that you remove any copies of the 
  26. software on the computer from which the copies were made; make copies of the 
  27. software for backup purposes only. 
  28.  
  29. XDS software and documentation have been tested and reviewed. Nevertheless, 
  30. xTech makes no warranty or representation, either express or implied, with 
  31. respect to the software and documentation included with XDS. In no event will 
  32. xTech be liable for direct, indirect, special, incidental or consequential 
  33. damages resulting from any defect in the software or documentation included 
  34. with this product. In particular, xTech shall have no liability for any 
  35. programs or data used with this product, including the cost of recovering 
  36. programs or data. 
  37.  
  38. XDS is a trademark of xTech Ltd. 
  39.  
  40. All trademarks and copyrights mentioned in this documentation are the property 
  41. of their respective holders. 
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 3. Introduction ΓòÉΓòÉΓòÉ
  45.  
  46.      About H2D 
  47.      Typographic conventions 
  48.  
  49.  
  50. ΓòÉΓòÉΓòÉ 3.1. About H2D ΓòÉΓòÉΓòÉ
  51.  
  52. Sooner or later, every Modula-2 programmer encounters four problems. These are: 
  53. absence, incompleteness, unportability, and low quality of libraries. At the 
  54. same time, C/C++ programmers usually have problems choosing from a huge set of 
  55. free, public domain, shareware, and commercial libraries of various purpose, 
  56. size, and quality which are in many cases portable or are available for a 
  57. number of platforms. Moreover, the Application Programming Interfaces (APIs) of 
  58. the most widely used software products (operating systems, database engines, 
  59. etc.), are defined in terms of the C programming language. 
  60.  
  61. In order to use all this stuff from Modula-2, a programmer needs, first, a 
  62. Modula-2 compiler which supports C calling/naming conventions and a set of 
  63. types corresponding to C types, and, second, definition modules corresponding 
  64. to the C headers of the library/API. Finding a suitable compiler is not a very 
  65. big deal, but manual conversion of C headers turns to a real nightmare when it 
  66. comes to, say, the X Window API. That is why we created H2D. 
  67.  
  68. H2D does the job automatically, i.e. translates C header files into Modula-2 
  69. definition modules. H2D is intended to be used with XDS version 2.10 or later 
  70. and is included in the XDS distribution package. However, the generated 
  71. definition modules may be used with any ISO-compliant Modula-2 compiler. The 
  72. required modifications are minor and may be done using text editor macros or a 
  73. simple REXX, sed, etc script. 
  74.  
  75. The source language is a subset of ANSI C, which includes declarations and 
  76. preprocessor directives, with some extensions (See Non-standard qualifiers and 
  77. Chapter Non-standard preprocessor directives). Destination language is ISO 
  78. Modula-2 with XDS language extensions, but in XDS resulting definition modules 
  79. may be used with both Modula-2 and Oberon-2. 
  80.  
  81. H2D generates definition modules suitable for either XDS-C, Native XDS, or 
  82. both. In case of Native XDS, module template for function-like C macros may be 
  83. generated (See Native code). In case of XDS-C, an extra header file containing 
  84. C declarations of types introduced by H2D is generated (See Convertor to C). 
  85.  
  86.  
  87. ΓòÉΓòÉΓòÉ 3.2. Typographic conventions ΓòÉΓòÉΓòÉ
  88.  
  89.      Language descriptions 
  90.      Source code fragments 
  91.  
  92.  
  93. ΓòÉΓòÉΓòÉ 3.2.1. Language descriptions ΓòÉΓòÉΓòÉ
  94.  
  95. Where formal descriptions for language syntax constructions appear, an extended 
  96. Backus-Naur Formalism (EBNF) is used. 
  97.  
  98. These descriptions are set in the Courier font. 
  99.  
  100. Text = Text [{Text}] | Text.
  101.  
  102. In EBNF, brackets [ and ] denote optionality of the enclosed expression, braces 
  103. { and } denote repetition (possibly 0 times), and the line | denotes other 
  104. possible valid descriptions. 
  105.  
  106. Non-terminal symbols start with an upper case letter (e.g. Statement). Terminal 
  107. symbols either start with a lower case letter (e.g. ident), or are written in 
  108. all upper case letters (e.g. BEGIN), or are enclosed within quotation marks 
  109. (e.g. ":="). 
  110.  
  111.  
  112. ΓòÉΓòÉΓòÉ 3.2.2. Source code fragments ΓòÉΓòÉΓòÉ
  113.  
  114. When fragments of a source code are used for examples or appear within a text 
  115. they are set in the Courier font. 
  116.  
  117. /* example.h */
  118.  
  119. typedef unsigned long int UINT;
  120.  
  121.  
  122. ΓòÉΓòÉΓòÉ 4. Configuring H2D ΓòÉΓòÉΓòÉ
  123.  
  124.      System search path 
  125.      Working configuration 
  126.      Directory hierarchies 
  127.      Redirection file 
  128.      Configuration file 
  129.      Customizing H2D messages 
  130.  
  131.  
  132. ΓòÉΓòÉΓòÉ 4.1. System search path ΓòÉΓòÉΓòÉ
  133.  
  134. In order that your operating system should know where to find the executable 
  135. binary files which constitute the H2D package, you have to setup your operating 
  136. system search path properly. Refer to the readme.1st file from the on-line 
  137. documentation. 
  138.  
  139.  
  140. ΓòÉΓòÉΓòÉ 4.2. Working configuration ΓòÉΓòÉΓòÉ
  141.  
  142. The H2D working configuration includes an executable file and a set of system 
  143. files: 
  144.  
  145. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  146.  h2d.red  Search path redirection file (See Redirection file)
  147.  
  148.  h2d.cfg  Configuration file (See Configuration file)
  149.  
  150.  h2d.msg  Contains texts of error messages (See Customizing H2D messages)
  151. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  152.  
  153. Upon invocation, H2D tries to locate the h2d.red file in the current directory. 
  154. If h2d.red is found, all other files are searched for/created using paths 
  155. defined in h2d.red, otherwise they are considered to reside in the current 
  156. directory. 
  157.  
  158. The configuration file contains various H2D settings. If the configuration file 
  159. is not found, default settings are used. 
  160.  
  161.  
  162. ΓòÉΓòÉΓòÉ 4.3. Directory hierarchies ΓòÉΓòÉΓòÉ
  163.  
  164. H2D gives you complete freedom over where you keep your header files and any 
  165. files which H2D itself creates for further use. It is advisable to work in a 
  166. project oriented fashion - i.e. to have a separate directory hierarchy for each 
  167. individual project. 
  168.  
  169. Each project should have a main working directory. The script called h2duser 
  170. can be used to create all required subdirectories and system files (e.g. 
  171. h2d.red). For example, to create a directory structure for a project called 
  172. myproj, issue the following commands: 
  173.  
  174. md myproj
  175. cd myproj
  176. h2duser
  177.  
  178. H2D keeps the directory hierarchies of original header files. Usually the 
  179. directory containing header files has some subdirectories. All H2D output 
  180. directories must contain the same subdirectories. ??? 
  181.  
  182.  
  183. ΓòÉΓòÉΓòÉ 4.4. Redirection file ΓòÉΓòÉΓòÉ
  184.  
  185. Upon activation, H2D looks for a file called h2d.red - the redirection file. 
  186. This file defines directories in which all other files are searched for. The 
  187. redirection file has to be placed in the current directory. 
  188.  
  189. A redirection file consists of several lines of the form: 
  190.  
  191. Pattern = directory {";" directory}
  192.  
  193. Pattern is a regular expression which all file names used by H2D will be 
  194. compared with. A regular expression is a string containing certain special 
  195. characters: 
  196.  
  197. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö